/**
 * @file wifi_configuration_ap.h
 * @brief Wi-Fi 配置热点管理器头文件
 * 
 * 该文件定义了Wi-Fi配置热点管理器类，用于在设备无法连接到Wi-Fi时
 * 启动配置热点，提供Web界面让用户配置Wi-Fi网络。
 * 
 * 主要功能：
 * - 创建Wi-Fi配置热点
 * - 启动Web服务器和配置界面
 * - 提供强制门户功能
 * - 支持SmartConfig一键配网
 * - 多语言支持
 * - 高级配置选项
 * 
 * @author SiaZhang
 * @version 2.4.2
 */

#ifndef _WIFI_CONFIGURATION_AP_H_
#define _WIFI_CONFIGURATION_AP_H_

#include <string>
#include <vector>
#include <mutex>

#include <esp_http_server.h>
#include <esp_event.h>
#include <esp_timer.h>
#include <esp_netif.h>
#include <esp_wifi_types_generic.h>

#include "dns_server.h"

/**
 * @brief Wi-Fi配置热点管理器类
 * 
 * 使用单例模式实现的Wi-Fi配置热点管理器，主要功能：
 * - 启动配置热点（SSID格式：前缀-MAC后6位）
 * - 创建Web配置界面，支持响应式设计
 * - 实现强制门户，自动重定向到配置页面
 * - 支持Wi-Fi网络扫描和显示
 * - 提供网络连接测试功能
 * - 支持SmartConfig（ESPTouch v2）一键配网
 * - 多语言界面支持（中文、英文、日文、繁体中文）
 * - 高级配置选项（功率管理、BSSID记忆等）
 * - 保存的网络管理（查看、删除、设为默认）
 */
class WifiConfigurationAp {
public:
    /**
     * @brief 获取单例实例
     * @return WifiConfigurationAp& 单例对象引用
     */
    static WifiConfigurationAp& GetInstance();

    /**
     * @brief 设置热点SSID前缀
     * 
     * @param ssid_prefix SSID前缀字符串
     * 
     * 完整的热点名称格式：{前缀}-{MAC地址后6位}
     * 例如：MyDevice-A1B2C3
     */
    void SetSsidPrefix(const std::string &&ssid_prefix);

    /**
     * @brief 设置Web界面语言
     * 
     * @param language 语言代码
     * 
     * 支持的语言：
     * - zh-CN: 简体中文
     * - en-US: 英文
     * - ja-JP: 日文  
     * - zh-TW: 繁体中文
     */
    void SetLanguage(const std::string &&language);

    /**
     * @brief 启动Wi-Fi配置热点
     * 
     * 启动流程：
     * 1. 创建Wi-Fi热点（开放网络）
     * 2. 启动Web服务器
     * 3. 启动DNS服务器（强制门户）
     * 4. 开始定时扫描Wi-Fi网络
     */
    void Start();

    /**
     * @brief 停止Wi-Fi配置热点
     * 
     * 清理所有资源，停止相关服务
     */
    void Stop();

    /**
     * @brief 启动SmartConfig配网
     * 
     * 启动ESP32 SmartConfig服务，支持ESPTouch v2协议。
     * 用户可以通过手机APP（如ESPTouch）进行一键配网。
     */
    void StartSmartConfig();

    /**
     * @brief 获取热点SSID名称
     * @return std::string 完整的热点SSID
     */
    std::string GetSsid();

    /**
     * @brief 获取Web服务器访问URL
     * @return std::string Web服务器URL（通常是http://192.168.4.1）
     */
    std::string GetWebServerUrl();

    // 禁用拷贝构造和赋值操作（单例模式）
    WifiConfigurationAp(const WifiConfigurationAp&) = delete;
    WifiConfigurationAp& operator=(const WifiConfigurationAp&) = delete;

private:
    /**
     * @brief 私有构造函数（单例模式）
     * 
     * 初始化成员变量和默认配置
     */
    WifiConfigurationAp();

    /**
     * @brief 私有析构函数（单例模式）
     * 
     * 清理资源和事件处理器
     */
    ~WifiConfigurationAp();

    std::mutex mutex_;                                          ///< 线程安全互斥锁
    DnsServer dns_server_;                                      ///< DNS服务器实例
    httpd_handle_t server_ = NULL;                              ///< HTTP服务器句柄
    EventGroupHandle_t event_group_;                            ///< FreeRTOS事件组句柄
    std::string ssid_prefix_;                                   ///< 热点SSID前缀
    std::string language_;                                      ///< Web界面语言
    esp_event_handler_instance_t instance_any_id_;             ///< Wi-Fi事件处理器实例
    esp_event_handler_instance_t instance_got_ip_;             ///< IP事件处理器实例
    esp_timer_handle_t scan_timer_ = nullptr;                  ///< Wi-Fi扫描定时器
    bool is_connecting_ = false;                                ///< 是否正在连接Wi-Fi标志
    esp_netif_t* ap_netif_ = nullptr;                          ///< AP网络接口句柄
    std::vector<wifi_ap_record_t> ap_records_;                 ///< Wi-Fi扫描结果列表

    // 高级配置选项
    std::string ota_url_;                                       ///< OTA升级URL
    int8_t max_tx_power_;                                       ///< 最大发射功率
    bool remember_bssid_;                                       ///< 是否记住BSSID

    /**
     * @brief 启动Wi-Fi热点
     * 
     * 配置并启动ESP32的AP模式：
     * - 设置IP地址为192.168.4.1
     * - 创建开放网络（无密码）
     * - 启动DHCP服务器
     * - 启动DNS服务器
     */
    void StartAccessPoint();

    /**
     * @brief 启动Web服务器
     * 
     * 创建HTTP服务器并注册所有路由：
     * - 主配置页面 (/)
     * - Wi-Fi扫描接口 (/scan)
     * - 网络连接接口 (/submit)
     * - 保存的网络管理接口 (/saved/)
     * - 高级配置接口 (/advanced/)
     * - 强制门户重定向
     * - 设备重启接口 (/reboot)
     */
    void StartWebServer();

    /**
     * @brief 尝试连接到指定Wi-Fi网络
     * 
     * @param ssid Wi-Fi网络名称
     * @param password Wi-Fi网络密码
     * @return bool 连接成功返回true，失败返回false
     * 
     * 测试网络连接，但不保存配置。
     * 连接成功后会立即断开，仅用于验证密码正确性。
     */
    bool ConnectToWifi(const std::string &ssid, const std::string &password);

    /**
     * @brief 保存Wi-Fi网络配置
     * 
     * @param ssid Wi-Fi网络名称
     * @param password Wi-Fi网络密码
     * 
     * 将网络配置保存到SSID管理器中，并持久化到NVS
     */
    void Save(const std::string &ssid, const std::string &password);

    /**
     * @brief Wi-Fi事件处理器（静态方法）
     * 
     * @param arg 用户参数（WifiConfigurationAp实例指针）
     * @param event_base 事件基础类型
     * @param event_id 事件ID
     * @param event_data 事件数据
     * 
     * 处理Wi-Fi相关事件：
     * - AP客户端连接/断开
     * - STA连接/断开（用于测试连接）
     * - 扫描完成
     */
    static void WifiEventHandler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data);

    /**
     * @brief IP事件处理器（静态方法）
     * 
     * @param arg 用户参数（WifiConfigurationAp实例指针）
     * @param event_base 事件基础类型
     * @param event_id 事件ID
     * @param event_data 事件数据
     * 
     * 处理IP相关事件，主要用于连接测试
     */
    static void IpEventHandler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data);

    /**
     * @brief SmartConfig事件处理器（静态方法）
     * 
     * @param arg 用户参数（WifiConfigurationAp实例指针）
     * @param event_base 事件基础类型
     * @param event_id 事件ID
     * @param event_data 事件数据
     * 
     * 处理SmartConfig相关事件：
     * - 扫描完成
     * - 发现配网信道
     * - 获取到SSID和密码
     * - 发送ACK确认
     */
    static void SmartConfigEventHandler(void* arg, esp_event_base_t event_base, 
                                      int32_t event_id, void* event_data);
    
    esp_event_handler_instance_t sc_event_instance_ = nullptr;  ///< SmartConfig事件处理器实例
};

#endif // _WIFI_CONFIGURATION_AP_H_
